home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
VS_804.ARJ
/
MAINTSRC.EXE
/
MAINT.DOC
< prev
next >
Wrap
Text File
|
1991-12-03
|
24KB
|
586 lines
Designing Your Clipper v5.01 Application
by Vernon E. Six, Jr.
December 3, 1991
CopyRight (c) 1991 by Vernon E. Six, Jr.
All Rights Reserved World Wide
Table Of Contents
First Things First . . . . . . . . . . . . . . . . . . . . . 3
Database Dictionaries . . . . . . . . . . . . . . . . . . . . 3
Database Dictionary Maintenance Utility . . . . . . . . . . . 5
Create Database / Edit Header Information . . . . . . . . . . 5
Define Fields . . . . . . . . . . . . . . . . . . . . . . . . 6
Define Indexs . . . . . . . . . . . . . . . . . . . . . . . . 7
Delete Database . . . . . . . . . . . . . . . . . . . . . . . 8
Generate *.CH Files - Preprocessor . . . . . . . . . . . . . 9
Print Structure . . . . . . . . . . . . . . . . . . . . . . . 12
Renumber . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
First Things First
The first step to designing your application is to determine
exactly what output you want your application to be able to
produce. This is where the interaction with your end user should
be the highest. You should try to obtain as much information as
possible relating to the desired reports, etc.
After you have determined what the output requirements are, you
should try to determine what data is necessary to obtain the
desired output. As you are collecting this information, try to
break the various pieces into logical groups. For example:
logical groups for an accounts receivable system would be
customers, invoices, payments, purchases, etc. This step is
crucial for it is only through this process that you can develop
your actual DBF file structures, index keys, etc.
After you have broken the data into logical groups, try to define
the relationships between the various groups. Example: An
invoice has a relationship to the customer file because we surely
would want to know to whom we sold something.
The next step is to build a database dictionary.
Database Dictionaries
After you have decided what it is you want your application to
do, you should design your database dictionary. In short, a
database dictionary is nothing more than data about data.
There are several advantages to using a database dictionary but
the single largest advantage is the ability to allow your various
functions to communicate with each other. i.e. UdfOne() might
only need one index file for a particular database, but UdfTwo()
needs several index files. By using a database dictionary,
UdfOne() will open all the index files and maintain them so they
are current for the next time UdfTwo() gets called and vice-
versa.
When using the Vern Six's Clipper ToolBox the database dictionary
will contain the following information about each database...
1) default path to the actual DBF file,
2) whether or not the application is allowed to re-create
a missing DBF file,
3) field definitions (data type, length, description,
etc),
4) default field values,
5) field picture statements (for use with @ SAY .. GET
statements, etc)
6) index file names, order and keys
You should design your database dictionary in such a way that
data within your application is not stored in multiple locations.
For example, you probably would not want to store customer
addresses with each invoice, but rather, you would store them in
a customer file and point to them from within the invoice file
with the use of an external key. The customer number in this
case would be consider an external key.
The entire datbase dictionary is contained in three database
files (remember... it's merely data about data). These
dictionary files are listed below with their associated file
structures and index keys.
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ _DictHdr.DBF File Structure │ │ _DictFld.Dbf File Structure │
│ # Field Name Type Len Dec │ │ # Field Name Type Len Dec │
├──────────────────────────────┤ ├──────────────────────────────┤
│ 1 DBF_NAME C 8 0 │ │ 1 DBF_NAME C 8 0 │
│ 2 DESC C 40 0 │ │ 2 FIELD_NMBR C 3 0 │
│ 3 CREATE L 1 0 │ │ 3 FIELD_NAME C 10 0 │
│ 4 PATH C 60 0 │ │ 4 FIELD_TYPE C 1 0 │
├──────────────────────────────┤ │ 5 FIELD_LEN N 3 0 │
│Index: │ │ 6 FIELD_DEC N 3 0 │
│ _DictHdr.Ntx: DBF_NAME │ │ 7 DESC C 40 0 │
└──────────────────────────────┘ │ 8 DEFAULT C 60 0 │
┌──────────────────────────────┐ │ 9 PICTURE C 60 0 │
│ _DictNtx.DBF File Structure │ ├──────────────────────────────┤
│ # Field Name Type Len Dec │ │Index: │
├──────────────────────────────┤ │ _DictFld: DBF_NAME+FIELD_NMBR│
│ 1 DBF_NAME C 8 0 │ │ _DictFl2: DBF_NAME+FIELD_NAME│
│ 2 ORDER C 2 0 │ └──────────────────────────────┘
│ 3 NTX_NAME C 8 0 │
│ 4 TYPE C 1 0 │
│ 5 KEY C 80 0 │
├──────────────────────────────┤
│Index: │
│ _DictNtx: DBF_NAME+ORDER │
└──────────────────────────────┘
These dictionary database files must be available to your
application at run time as several functions in Vern Six's
Clipper ToolBox will be accessing them. These databases allow
not only different functions within the same application to
communicate amongst themselves, they also allow completely
different applications to communicate. Example: If one
application is an Accounts Receivable system and another
application is a form letter generator, they could both access
the same customer file via these database dictionary databases.
NOTE: You can set an environment variable to point to a different
directory if you do not want your database dictionary files in
the current directory. Example: "SET DATADICT=C:\DATADICT\"
Database Dictionary Maintenance Utility
Vern Six's Clipper Toolbox comes with its own database dictionary
maintenance utility called Maint.Exe. This utility will allow
you to quickly and easily create and maintain your datbase
dictionary. Of course, you could also create these dictionary
databases with something like DBU.EXE or the like, but you really
should be using MAint.Exe since it has some other features and
will ensure data itegrity, etc. by not allowing you to forget
something or create something incorrectly.
The main screen within Maint.Exe is a pick list of all the
databases in your application (figure 1). The following keys are
active from this main screen...
F1 - Help
F4 - Copy
F5 - Renumber
F6 - Print Structure
F7 - Generate *.CH Files
F8 - Define Fields
F9 - Define Indexs
F10 - Edit Header Information
Ins - Create Database
Del - Delete Database
Create Database / Edit Header Information
Pressing either [Insert] or the [F10] key will take to the screen
shown in figure 2. If you pressed the [Insert] key, you will be
prompted for information about the new database you are creating.
If you pressed [F10] you will be able to edit the information
associated with the currently highlighted database.
In either case, you will be prompted for the name, description,
re-create setting, and default path for the specified database.
The answers to these queries should be self explanatory with the
exception of the default path. You would normally want to leave
this field blank if you are going to be running your application
in the same directory as your database files. Note: The user can
override the default path setting by setting an environment
variable such as "SET CUST=C:\DATA\ACCT\"
After you have provided this basic information about the database
file, you will be returned to the main screen of Maint.Exe.
Define Fields
You can create the actual database structure by pressing the [F8]
key from the Maint.Exe main pick list. This will cause the
structure pick list to be presented (figure 3). From here, you
can press the [Insert] key to add a new field, the [Delete] key
to delete a field, or the [F10] key to edit the currently
selected field.
When you either create or edit a field, you will be taken to the
screen shown in figure 4. Each field is described in detail
below...
Nmbr is a programmer defined field that should contain the field
number. I suggest that you number your fields in increments of
five or ten so you can come back to this database and insert new
fields in between existing fields. You should pad Nmbr with
zeros on the left.
Field Name is the actual name of the field and must conform to
Clipper's field naming conventions. Field Name must be in all
upper case.
Type is the field type and must conform to Clipper's field type
conventions. The valid choices are... C - Character, N -
Numeric, L - Logical, D - Date, M - Memo. Type must also be in
upper case.
Length is a numeric value representing the entire field length
(including any decimals points, etc.)
Dec is a numeric value that represents the number of digits to
the right of the decimal place. Dec is only valid for fields of
Type N - Numeric.
Description is a programmer defined description of what this
field is for. You should try to be descriptive as this is the
same field the users will see when they build an interactive
query.
Default Value is a programmer defined default value that VSG
(Vern Six's Code Generator) will place in the field when it
creates a "new" record. The value you place here must be of the
same type as the field itself. i.e. strings have to be in
quotes, etc.
Picture Clause is a programmer defined picture clause that VSG
will use when displaying/editing this field. The value you place
here must be "stringified". i.e. a picture statement of 9999
must be written as "9999".
NOTE: You can also reference the default value and picture
statement in your own programs through the use of the database
dictionary "include" files (see Pre-Processor below).
Pressing [Escape] from the "database fields" pick list will
return you to the Maint.Exe main screen/pick list.
Define Indexs
You can define the various index files that are required within
your application(s) by pressing the [F9] key from the Maint.Exe
main pick list. This will cause the index pick list to be
presented (figure 5). From here, you can press the [Insert] key
to add a new index, the [Delete] key to delete an index file, or
the [F10] key to edit the currently selected index.
When you either create or edit an index file, you will be taken
to the screen shown in figure 6. Each field is described in
detail below...
Index FileName is a character field that should contain the
actual name of the index file. Do not put the NTX extension on
the end of this filename.
Order is a character field that is used to determine the order in
which the index files will be opened. This field should be a
number padded on the left with a zero (if needed).
Type is a character field that should contain the type of the
index key. N - Numeric, C - Character, D - Date, L - Logical
Key is the actual index key expression. You should place
parenthesis around keys that are "simple" in nature (one field).
While you are entering this field, you can press the [F5] key to
select a field from a list.
Delete Database
Pressing the [Delete] key at the Maint.Exe main pick list will
delete the currently highlighted database. You will be prompted
to ensure this is really what you want to do. Once you delete
the database, there is no way to recover it.
Generate *.CH Files - Preprocessor
Maint.Exe will generate "include" files for use in your programs
and especially for use in VSG (Vern Six's Code Generator)
generated programs. In general, you should generate the database
dictionary include files after you have defined all the databases
in your application and WHENEVER you change the database
dictionary. To generate the include files, press [F7] from the
main pick list in Maint.Exe.
A sample include file might look like this...
* Filename......: CUST.CH
*
* Author........: Vernon E. Six, Jr.
*
* Last Update...: 10/20/91 21:34:45
*
* Notice........: Copyright (c) 1991 by Vernon E. Six, Jr.
* All Rights Reserved World Wide
*
* Purpose.......: Data Dictionary DEFINEs for CUST.DBF
#DEFINE _DEF_CUST_CODE SPACE(5)
#DEFINE _DEF_CUST_NAME SPACE(35)
#DEFINE _DEF_CUST_ADDR1 SPACE(35)
#DEFINE _DEF_CUST_ADDR2 SPACE(35)
#DEFINE _DEF_CUST_ZIP SPACE(5)
#DEFINE _DEF_CUST_PHONE SPACE(14)
#DEFINE _DEF_CUST_CONTACT SPACE(30)
#DEFINE _DEF_CUST_COMMENTS SPACE(50)
#DEFINE _DEF_CUST_LAST_PYMT DATE()
#DEFINE _DEF_CUST_PYMT_AMT 0
#DEFINE _DEF_CUST_CURR_BAL 0
#DEFINE _DEF_CUST_PAST_DUE30 0
#DEFINE _DEF_CUST_PAST_DUE60 0
#DEFINE _DEF_CUST_PAST_DUE90 0
#DEFINE _DEF_CUST_BALANCE 0
#DEFINE _DEF_CUST_TTL_PYMTS 0
#DEFINE _DEF_CUST_TTL_CHGS 0
#DEFINE _DEF_CUST_ACCT_LOCK .F.
#DEFINE _PIC_CUST_CODE "!!!!!"
#DEFINE _PIC_CUST_NAME REPLICATE("X",35)
#DEFINE _PIC_CUST_ADDR1 REPLICATE("X",35)
#DEFINE _PIC_CUST_ADDR2 REPLICATE("X",35)
#DEFINE _PIC_CUST_ZIP REPLICATE("X",5)
#DEFINE _PIC_CUST_PHONE "(999) 999-9999"
#DEFINE _PIC_CUST_CONTACT REPLICATE("X",30)
#DEFINE _PIC_CUST_COMMENTS REPLICATE("X",50)
#DEFINE _PIC_CUST_LAST_PYMT "99/99/99"
#DEFINE _PIC_CUST_PYMT_AMT "9999.99"
#DEFINE _PIC_CUST_CURR_BAL "9999999.99"
#DEFINE _PIC_CUST_PAST_DUE30 "9999999.99"
#DEFINE _PIC_CUST_PAST_DUE60 "9999999.99"
#DEFINE _PIC_CUST_PAST_DUE90 "9999999.99"
#DEFINE _PIC_CUST_BALANCE "9999999.99"
#DEFINE _PIC_CUST_TTL_PYMTS "9999999.99"
#DEFINE _PIC_CUST_TTL_CHGS "9999999.99"
#DEFINE _PIC_CUST_ACCT_LOCK "Y"
The following is a sample program that uses this include file...
* Filename......: AddCust.Prg
*
* Author........: Vernon E. Six, Jr.
*
* Last Update...: Thu 10-24-1991 19:27:49
*
* Notice........: Copyright (c) 1991 by Vernon E. Six, Jr.
* All Rights Reserved World Wide
*
*
* Dialect.......: Clipper v5.01
#include "INKEY.CH"
#include "CUST.CH"
FUNCTION AddCust()
*****
* Simple routine to demonstrate use of data dictionary and related functions
* for dCUG() "Saturday Gang"
*****
LOCAL getlist := {}
LOCAL c_CustCode := _DEF_CUST_CODE
LOCAL l_AcctLock := _DEF_CUST_ACCT_LOCK
LOCAL c_Name := _DEF_CUST_NAME
LOCAL c_Addr1 := _DEF_CUST_ADDR1
LOCAL c_Addr2 := _DEF_CUST_ADDR2
LOCAL c_Zip := _DEF_CUST_ZIP
LOCAL c_Phone := _DEF_CUST_PHONE
LOCAL c_Contact := _DEF_CUST_CONTACT
LOCAL c_Comments := _DEF_CUST_COMMENTS
//
// Open the customer database
//
IF .NOT. VS_OpenDbf( "CUST" )
VS_Die( PADC("Which Way Did It Go?",40),PADC("Which Way Did It Go?",40) )
ENDIF
VS_NewScrn()
@ 05,05 SAY "Customer Code: " GET c_CustCode PICTURE _PIC_CUST_CODE
@ 06,05 SAY "Account Locked? " GET l_AcctLock PICTURE _PIC_CUST_ACCT_LOCK
@ 10,05 SAY "Street Address: " GET c_Addr1 PICTURE _PIC_CUST_ADDR1
@ 11,05 SAY "Box, suite, etc: " GET c_Addr2 PICTURE _PIC_CUST_ADDR2
@ 12,05 SAY "Zip Code: " GET c_Zip PICTURE _PIC_CUST_ZIP
@ 15,05 SAY "Telephone: " GET c_Phone PICTURE _PIC_CUST_PHONE
@ 16,05 SAY "Contact: " GET c_Contact PICTURE _PIC_CUST_CONTACT
@ 20,05 SAY "Cmts: " GET c_Comments PICTURE _PIC_CUST_COMMENTS
READ
BEGIN SEQUENCE
IF LASTKEY() = K_ESC
BREAK
ENDIF
IF .NOT. CUST->( VS_AddRec() )
BREAK
ENDIF
REPLACE CUST->CODE WITH c_CustCode
REPLACE CUST->ACCT_LOCK WITH l_AcctLock
REPLACE CUST->NAME WITH c_Name
REPLACE CUST->ADDR1 WITH c_Addr1
REPLACE CUST->ADDR2 WITH c_Addr2
REPLACE CUST->ZIP WITH c_Zip
REPLACE CUST->PHONE WITH c_Phone
REPLACE CUST->CONTACT WITH c_Contact
REPLACE CUST->COMMENTS WITH c_Comments
CUST->( dbUnlock() )
END SEQUENCE
dbCloseAll()
RETURN(NIL)
*** EOF: AddCust() **********************************************************
Print Structure
Pressing the [F6] key at the main pick list in Maint.Exe will
cause the file structure and index keys for the currently
selected database to be printed to the printer on LPT1:. You
will be prompted for the printer name, etc.
Renumber
Pressing the [F5] key at the main pick list in Maint.Exe will
cause Maint.Exe to assign new sequence numbers to the fields in
the currently selected database. This is most commonly used when
you have added several new fields to a database and have
exhausted the number of fields you can insert between two fields.
i.e. If you need to insert a field between field number "005"
and field number "006", you could not do it. Renumber will
spread these tightly grouped fields apart again. In this
example, 5 would remain as 5 and 6 would become 10, 7 would
become 15, 8 would be come 20, etc.
Copy
Pressing [F4] will allow you to copy the currently selected
database structure and index keys to a new database structure,
etc. This is useful for when you create a database and later
need a similar database that only requires a few modifications to
the structure.
WARNING!! If you copy a database, you have also copied the index
file names, keys, etc. Be sure to edit the index files for the
new database, or you will have two databases sharing an index
file. This is most certainly a one way ticket to ErrorSys() at
runtime.